//
//  OCHamcrest - HCMatcher.h
//  Copyright 2013 hamcrest.org. See LICENSE.txt
//
//  Created by: Jon Reid, http://qualitycoding.org/
//  Docs: http://hamcrest.github.com/OCHamcrest/
//  Source: https://github.com/hamcrest/OCHamcrest
//

#import "HCSelfDescribing.h"


/**
 A matcher over acceptable values.
 
 A matcher is able to describe itself to give feedback when it fails.
 
 HCMatcher implementations should @b not directly implement this protocol.
 Instead, @b extend the HCBaseMatcher class, which will ensure that the HCMatcher API can grow
 to support new features and remain compatible with all HCMatcher implementations.
 
 @ingroup core
 */
@protocol HCMatcher <HCSelfDescribing>

/**
 Evaluates the matcher for argument @a item.
 
 @param item  The object against which the matcher is evaluated.
 @return @c YES if @a item matches, otherwise @c NO.
 */
- (BOOL)matches:(id)item;

/**
 Evaluates the matcher for argument @a item.
 
 @param item                 The object against which the matcher is evaluated.
 @param mismatchDescription  The description to be built or appended to if @a item does not match.
 @return @c YES if @a item matches, otherwise @c NO.
 */
- (BOOL)matches:(id)item describingMismatchTo:(id<HCDescription>)mismatchDescription;

/**
 Generates a description of why the matcher has not accepted the item.
 
 The description will be part of a larger description of why a matching failed, so it should be
 concise.
 
 This method assumes that @c matches:item is false, but will not check this.
 
 @param item                 The item that the HCMatcher has rejected.
 @param mismatchDescription  The description to be built or appended to.
 */
- (void)describeMismatchOf:(id)item to:(id<HCDescription>)mismatchDescription;

@end
